1use anyhow::{Context as _, Result};
2use collections::HashMap;
3pub use gpui_macros::Action;
4pub use no_action::{NoAction, is_no_action};
5use serde_json::json;
6use std::{
7 any::{Any, TypeId},
8 fmt::Display,
9};
10
11/// Defines and registers unit structs that can be used as actions. For more complex data types, derive `Action`.
12///
13/// For example:
14///
15/// ```
16/// actions!(editor, [MoveUp, MoveDown, MoveLeft, MoveRight, Newline]);
17/// ```
18///
19/// This will create actions with names like `editor::MoveUp`, `editor::MoveDown`, etc.
20///
21/// The namespace argument `editor` can also be omitted, though it is required for Zed actions.
22#[macro_export]
23macro_rules! actions {
24 ($namespace:path, [ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
25 $(
26 #[derive(::std::clone::Clone, ::std::cmp::PartialEq, ::std::default::Default, ::std::fmt::Debug, gpui::Action)]
27 #[action(namespace = $namespace)]
28 $(#[$attr])*
29 pub struct $name;
30 )*
31 };
32 ([ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
33 $(
34 #[derive(::std::clone::Clone, ::std::cmp::PartialEq, ::std::default::Default, ::std::fmt::Debug, gpui::Action)]
35 $(#[$attr])*
36 pub struct $name;
37 )*
38 };
39}
40
41/// Actions are used to implement keyboard-driven UI. When you declare an action, you can bind keys
42/// to the action in the keymap and listeners for that action in the element tree.
43///
44/// To declare a list of simple actions, you can use the actions! macro, which defines a simple unit
45/// struct action for each listed action name in the given namespace.
46///
47/// ```
48/// actions!(editor, [MoveUp, MoveDown, MoveLeft, MoveRight, Newline]);
49/// ```
50///
51/// # Derive Macro
52///
53/// More complex data types can also be actions, by using the derive macro for `Action`:
54///
55/// ```
56/// #[derive(Clone, PartialEq, serde::Deserialize, schemars::JsonSchema, Action)]
57/// #[action(namespace = editor)]
58/// pub struct SelectNext {
59/// pub replace_newest: bool,
60/// }
61/// ```
62///
63/// The derive macro for `Action` requires that the type implement `Clone` and `PartialEq`. It also
64/// requires `serde::Deserialize` and `schemars::JsonSchema` unless `#[action(no_json)]` is
65/// specified. In Zed these trait impls are used to load keymaps from JSON.
66///
67/// Multiple arguments separated by commas may be specified in `#[action(...)]`:
68///
69/// - `namespace = some_namespace` sets the namespace. In Zed this is required.
70///
71/// - `name = "ActionName"` overrides the action's name. This must not contain `::`.
72///
73/// - `no_json` causes the `build` method to always error and `action_json_schema` to return `None`,
74/// and allows actions not implement `serde::Serialize` and `schemars::JsonSchema`.
75///
76/// - `no_register` skips registering the action. This is useful for implementing the `Action` trait
77/// while not supporting invocation by name or JSON deserialization.
78///
79/// - `deprecated_aliases = ["editor::SomeAction"]` specifies deprecated old names for the action.
80/// These action names should *not* correspond to any actions that are registered. These old names
81/// can then still be used to refer to invoke this action. In Zed, the keymap JSON schema will
82/// accept these old names and provide warnings.
83///
84/// - `deprecated = "Message about why this action is deprecation"` specifies a deprecation message.
85/// In Zed, the keymap JSON schema will cause this to be displayed as a warning.
86///
87/// # Manual Implementation
88///
89/// If you want to control the behavior of the action trait manually, you can use the lower-level
90/// `#[register_action]` macro, which only generates the code needed to register your action before
91/// `main`.
92///
93/// ```
94/// #[derive(gpui::private::serde::Deserialize, std::cmp::PartialEq, std::clone::Clone)]
95/// pub struct Paste {
96/// pub content: SharedString,
97/// }
98///
99/// impl gpui::Action for Paste {
100/// ///...
101/// }
102/// register_action!(Paste);
103/// ```
104pub trait Action: Any + Send {
105 /// Clone the action into a new box
106 fn boxed_clone(&self) -> Box<dyn Action>;
107
108 /// Do a partial equality check on this action and the other
109 fn partial_eq(&self, action: &dyn Action) -> bool;
110
111 /// Get the name of this action, for displaying in UI
112 fn name(&self) -> &'static str;
113
114 /// Get the name of this action type (static)
115 fn name_for_type() -> &'static str
116 where
117 Self: Sized;
118
119 /// Build this action from a JSON value. This is used to construct actions from the keymap.
120 /// A value of `{}` will be passed for actions that don't have any parameters.
121 fn build(value: serde_json::Value) -> Result<Box<dyn Action>>
122 where
123 Self: Sized;
124
125 /// Optional JSON schema for the action's input data.
126 fn action_json_schema(
127 _: &mut schemars::r#gen::SchemaGenerator,
128 ) -> Option<schemars::schema::Schema>
129 where
130 Self: Sized,
131 {
132 None
133 }
134
135 /// A list of alternate, deprecated names for this action. These names can still be used to
136 /// invoke the action. In Zed, the keymap JSON schema will accept these old names and provide
137 /// warnings.
138 fn deprecated_aliases() -> &'static [&'static str]
139 where
140 Self: Sized,
141 {
142 &[]
143 }
144
145 /// Returns the deprecation message for this action, if any. In Zed, the keymap JSON schema will
146 /// cause this to be displayed as a warning.
147 fn deprecation_message() -> Option<&'static str>
148 where
149 Self: Sized,
150 {
151 None
152 }
153}
154
155impl std::fmt::Debug for dyn Action {
156 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
157 f.debug_struct("dyn Action")
158 .field("name", &self.name())
159 .finish()
160 }
161}
162
163impl dyn Action {
164 /// Type-erase Action type.
165 pub fn as_any(&self) -> &dyn Any {
166 self as &dyn Any
167 }
168}
169
170/// Error type for `Keystroke::parse`. This is used instead of `anyhow::Error` so that Zed can use
171/// markdown to display it.
172#[derive(Debug)]
173pub enum ActionBuildError {
174 /// Indicates that an action with this name has not been registered.
175 NotFound {
176 /// Name of the action that was not found.
177 name: String,
178 },
179 /// Indicates that an error occurred while building the action, typically a JSON deserialization
180 /// error.
181 BuildError {
182 /// Name of the action that was attempting to be built.
183 name: String,
184 /// Error that occurred while building the action.
185 error: anyhow::Error,
186 },
187}
188
189impl std::error::Error for ActionBuildError {
190 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
191 match self {
192 ActionBuildError::NotFound { .. } => None,
193 ActionBuildError::BuildError { error, .. } => error.source(),
194 }
195 }
196}
197
198impl Display for ActionBuildError {
199 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
200 match self {
201 ActionBuildError::NotFound { name } => {
202 write!(f, "Didn't find an action named \"{name}\"")
203 }
204 ActionBuildError::BuildError { name, error } => {
205 write!(f, "Error while building action \"{name}\": {error}")
206 }
207 }
208 }
209}
210
211type ActionBuilder = fn(json: serde_json::Value) -> anyhow::Result<Box<dyn Action>>;
212
213pub(crate) struct ActionRegistry {
214 by_name: HashMap<&'static str, ActionData>,
215 names_by_type_id: HashMap<TypeId, &'static str>,
216 all_names: Vec<&'static str>, // So we can return a static slice.
217 deprecated_aliases: HashMap<&'static str, &'static str>, // deprecated name -> preferred name
218 deprecation_messages: HashMap<&'static str, &'static str>, // action name -> deprecation message
219}
220
221impl Default for ActionRegistry {
222 fn default() -> Self {
223 let mut this = ActionRegistry {
224 by_name: Default::default(),
225 names_by_type_id: Default::default(),
226 all_names: Default::default(),
227 deprecated_aliases: Default::default(),
228 deprecation_messages: Default::default(),
229 };
230
231 this.load_actions();
232
233 this
234 }
235}
236
237struct ActionData {
238 pub build: ActionBuilder,
239 pub json_schema: fn(&mut schemars::r#gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
240}
241
242/// This type must be public so that our macros can build it in other crates.
243/// But this is an implementation detail and should not be used directly.
244#[doc(hidden)]
245pub struct MacroActionBuilder(pub fn() -> MacroActionData);
246
247/// This type must be public so that our macros can build it in other crates.
248/// But this is an implementation detail and should not be used directly.
249#[doc(hidden)]
250pub struct MacroActionData {
251 pub name: &'static str,
252 pub type_id: TypeId,
253 pub build: ActionBuilder,
254 pub json_schema: fn(&mut schemars::r#gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
255 pub deprecated_aliases: &'static [&'static str],
256 pub deprecation_message: Option<&'static str>,
257}
258
259inventory::collect!(MacroActionBuilder);
260
261impl ActionRegistry {
262 /// Load all registered actions into the registry.
263 pub(crate) fn load_actions(&mut self) {
264 for builder in inventory::iter::<MacroActionBuilder> {
265 let action = builder.0();
266 self.insert_action(action);
267 }
268 }
269
270 #[cfg(test)]
271 pub(crate) fn load_action<A: Action>(&mut self) {
272 self.insert_action(MacroActionData {
273 name: A::name_for_type(),
274 type_id: TypeId::of::<A>(),
275 build: A::build,
276 json_schema: A::action_json_schema,
277 deprecated_aliases: A::deprecated_aliases(),
278 deprecation_message: A::deprecation_message(),
279 });
280 }
281
282 fn insert_action(&mut self, action: MacroActionData) {
283 self.by_name.insert(
284 action.name,
285 ActionData {
286 build: action.build,
287 json_schema: action.json_schema,
288 },
289 );
290 for &alias in action.deprecated_aliases {
291 self.by_name.insert(
292 alias,
293 ActionData {
294 build: action.build,
295 json_schema: action.json_schema,
296 },
297 );
298 self.deprecated_aliases.insert(alias, action.name);
299 self.all_names.push(alias);
300 }
301 self.names_by_type_id.insert(action.type_id, action.name);
302 self.all_names.push(action.name);
303 if let Some(deprecation_msg) = action.deprecation_message {
304 self.deprecation_messages
305 .insert(action.name, deprecation_msg);
306 }
307 }
308
309 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
310 pub fn build_action_type(&self, type_id: &TypeId) -> Result<Box<dyn Action>> {
311 let name = self
312 .names_by_type_id
313 .get(type_id)
314 .with_context(|| format!("no action type registered for {type_id:?}"))?;
315
316 Ok(self.build_action(name, None)?)
317 }
318
319 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
320 pub fn build_action(
321 &self,
322 name: &str,
323 params: Option<serde_json::Value>,
324 ) -> std::result::Result<Box<dyn Action>, ActionBuildError> {
325 let build_action = self
326 .by_name
327 .get(name)
328 .ok_or_else(|| ActionBuildError::NotFound {
329 name: name.to_owned(),
330 })?
331 .build;
332 (build_action)(params.unwrap_or_else(|| json!({}))).map_err(|e| {
333 ActionBuildError::BuildError {
334 name: name.to_owned(),
335 error: e,
336 }
337 })
338 }
339
340 pub fn all_action_names(&self) -> &[&'static str] {
341 self.all_names.as_slice()
342 }
343
344 pub fn action_schemas(
345 &self,
346 generator: &mut schemars::r#gen::SchemaGenerator,
347 ) -> Vec<(&'static str, Option<schemars::schema::Schema>)> {
348 // Use the order from all_names so that the resulting schema has sensible order.
349 self.all_names
350 .iter()
351 .map(|name| {
352 let action_data = self
353 .by_name
354 .get(name)
355 .expect("All actions in all_names should be registered");
356 (*name, (action_data.json_schema)(generator))
357 })
358 .collect::<Vec<_>>()
359 }
360
361 pub fn deprecated_aliases(&self) -> &HashMap<&'static str, &'static str> {
362 &self.deprecated_aliases
363 }
364
365 pub fn deprecation_messages(&self) -> &HashMap<&'static str, &'static str> {
366 &self.deprecation_messages
367 }
368}
369
370/// Generate a list of all the registered actions.
371/// Useful for transforming the list of available actions into a
372/// format suited for static analysis such as in validating keymaps, or
373/// generating documentation.
374pub fn generate_list_of_all_registered_actions() -> Vec<MacroActionData> {
375 let mut actions = Vec::new();
376 for builder in inventory::iter::<MacroActionBuilder> {
377 actions.push(builder.0());
378 }
379 actions
380}
381
382mod no_action {
383 use crate as gpui;
384 use std::any::Any as _;
385
386 actions!(
387 zed,
388 [
389 /// Action with special handling which unbinds the keybinding this is associated with,
390 /// if it is the highest precedence match.
391 NoAction
392 ]
393 );
394
395 /// Returns whether or not this action represents a removed key binding.
396 pub fn is_no_action(action: &dyn gpui::Action) -> bool {
397 action.as_any().type_id() == (NoAction {}).type_id()
398 }
399}