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