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