1use crate::SharedString;
2use anyhow::{anyhow, Context, Result};
3use collections::HashMap;
4pub use no_action::{is_no_action, NoAction};
5use serde_json::json;
6use std::any::{Any, TypeId};
7
8/// Actions are used to implement keyboard-driven UI.
9/// When you declare an action, you can bind keys to the action in the keymap and
10/// listeners for that action in the element tree.
11///
12/// To declare a list of simple actions, you can use the actions! macro, which defines a simple unit struct
13/// action for each listed action name in the given namespace.
14/// ```rust
15/// actions!(editor, [MoveUp, MoveDown, MoveLeft, MoveRight, Newline]);
16/// ```
17/// More complex data types can also be actions, providing they implement Clone, PartialEq,
18/// and serde_derive::Deserialize.
19/// Use `impl_actions!` to automatically implement the action in the given namespace.
20/// ```
21/// #[derive(Clone, PartialEq, serde_derive::Deserialize)]
22/// pub struct SelectNext {
23/// pub replace_newest: bool,
24/// }
25/// impl_actions!(editor, [SelectNext]);
26/// ```
27///
28/// If you want to control the behavior of the action trait manually, you can use the lower-level `#[register_action]`
29/// macro, which only generates the code needed to register your action before `main`.
30///
31/// ```
32/// #[derive(gpui::private::serde::Deserialize, std::cmp::PartialEq, std::clone::Clone)]
33/// pub struct Paste {
34/// pub content: SharedString,
35/// }
36///
37/// impl gpui::Action for Paste {
38/// ///...
39/// }
40/// register_action!(Paste);
41/// ```
42pub trait Action: 'static + Send {
43 /// Clone the action into a new box
44 fn boxed_clone(&self) -> Box<dyn Action>;
45
46 /// Cast the action to the any type
47 fn as_any(&self) -> &dyn Any;
48
49 /// Do a partial equality check on this action and the other
50 fn partial_eq(&self, action: &dyn Action) -> bool;
51
52 /// Get the name of this action, for displaying in UI
53 fn name(&self) -> &str;
54
55 /// Get the name of this action for debugging
56 fn debug_name() -> &'static str
57 where
58 Self: Sized;
59
60 /// Build this action from a JSON value. This is used to construct actions from the keymap.
61 /// A value of `{}` will be passed for actions that don't have any parameters.
62 fn build(value: serde_json::Value) -> Result<Box<dyn Action>>
63 where
64 Self: Sized;
65
66 /// Optional JSON schema for the action's input data.
67 fn action_json_schema(
68 _: &mut schemars::gen::SchemaGenerator,
69 ) -> Option<schemars::schema::Schema>
70 where
71 Self: Sized,
72 {
73 None
74 }
75
76 /// A list of alternate, deprecated names for this action.
77 fn deprecated_aliases() -> &'static [&'static str]
78 where
79 Self: Sized,
80 {
81 &[]
82 }
83}
84
85impl std::fmt::Debug for dyn Action {
86 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
87 f.debug_struct("dyn Action")
88 .field("name", &self.name())
89 .finish()
90 }
91}
92
93impl dyn Action {
94 /// Get the type id of this action
95 pub fn type_id(&self) -> TypeId {
96 self.as_any().type_id()
97 }
98}
99
100type ActionBuilder = fn(json: serde_json::Value) -> anyhow::Result<Box<dyn Action>>;
101
102pub(crate) struct ActionRegistry {
103 by_name: HashMap<SharedString, ActionData>,
104 names_by_type_id: HashMap<TypeId, SharedString>,
105 all_names: Vec<SharedString>, // So we can return a static slice.
106 deprecations: HashMap<SharedString, SharedString>,
107}
108
109impl Default for ActionRegistry {
110 fn default() -> Self {
111 let mut this = ActionRegistry {
112 by_name: Default::default(),
113 names_by_type_id: Default::default(),
114 all_names: Default::default(),
115 deprecations: Default::default(),
116 };
117
118 this.load_actions();
119
120 this
121 }
122}
123
124struct ActionData {
125 pub build: ActionBuilder,
126 pub json_schema: fn(&mut schemars::gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
127}
128
129/// This type must be public so that our macros can build it in other crates.
130/// But this is an implementation detail and should not be used directly.
131#[doc(hidden)]
132pub type MacroActionBuilder = fn() -> MacroActionData;
133
134/// This type must be public so that our macros can build it in other crates.
135/// But this is an implementation detail and should not be used directly.
136#[doc(hidden)]
137pub struct MacroActionData {
138 pub name: &'static str,
139 pub aliases: &'static [&'static str],
140 pub type_id: TypeId,
141 pub build: ActionBuilder,
142 pub json_schema: fn(&mut schemars::gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
143}
144
145/// This constant must be public to be accessible from other crates.
146/// But its existence is an implementation detail and should not be used directly.
147#[doc(hidden)]
148#[linkme::distributed_slice]
149pub static __GPUI_ACTIONS: [MacroActionBuilder];
150
151impl ActionRegistry {
152 /// Load all registered actions into the registry.
153 pub(crate) fn load_actions(&mut self) {
154 for builder in __GPUI_ACTIONS {
155 let action = builder();
156 self.insert_action(action);
157 }
158 }
159
160 #[cfg(test)]
161 pub(crate) fn load_action<A: Action>(&mut self) {
162 self.insert_action(MacroActionData {
163 name: A::debug_name(),
164 aliases: A::deprecated_aliases(),
165 type_id: TypeId::of::<A>(),
166 build: A::build,
167 json_schema: A::action_json_schema,
168 });
169 }
170
171 fn insert_action(&mut self, action: MacroActionData) {
172 let name: SharedString = action.name.into();
173 self.by_name.insert(
174 name.clone(),
175 ActionData {
176 build: action.build,
177 json_schema: action.json_schema,
178 },
179 );
180 for &alias in action.aliases {
181 let alias: SharedString = alias.into();
182 self.by_name.insert(
183 alias.clone(),
184 ActionData {
185 build: action.build,
186 json_schema: action.json_schema,
187 },
188 );
189 self.deprecations.insert(alias.clone(), name.clone());
190 self.all_names.push(alias);
191 }
192 self.names_by_type_id.insert(action.type_id, name.clone());
193 self.all_names.push(name);
194 }
195
196 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
197 pub fn build_action_type(&self, type_id: &TypeId) -> Result<Box<dyn Action>> {
198 let name = self
199 .names_by_type_id
200 .get(type_id)
201 .ok_or_else(|| anyhow!("no action type registered for {:?}", type_id))?
202 .clone();
203
204 self.build_action(&name, None)
205 }
206
207 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
208 pub fn build_action(
209 &self,
210 name: &str,
211 params: Option<serde_json::Value>,
212 ) -> Result<Box<dyn Action>> {
213 let build_action = self
214 .by_name
215 .get(name)
216 .ok_or_else(|| anyhow!("No action type registered for {}", name))?
217 .build;
218 (build_action)(params.unwrap_or_else(|| json!({})))
219 .with_context(|| format!("Attempting to build action {}", name))
220 }
221
222 pub fn all_action_names(&self) -> &[SharedString] {
223 self.all_names.as_slice()
224 }
225
226 pub fn action_schemas(
227 &self,
228 generator: &mut schemars::gen::SchemaGenerator,
229 ) -> Vec<(SharedString, Option<schemars::schema::Schema>)> {
230 // Use the order from all_names so that the resulting schema has sensible order.
231 self.all_names
232 .iter()
233 .map(|name| {
234 let action_data = self
235 .by_name
236 .get(name)
237 .expect("All actions in all_names should be registered");
238 (name.clone(), (action_data.json_schema)(generator))
239 })
240 .collect::<Vec<_>>()
241 }
242
243 pub fn action_deprecations(&self) -> &HashMap<SharedString, SharedString> {
244 &self.deprecations
245 }
246}
247
248/// Defines and registers unit structs that can be used as actions.
249///
250/// To use more complex data types as actions, use `impl_actions!`
251#[macro_export]
252macro_rules! actions {
253 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
254 $(
255 // Unfortunately rust-analyzer doesn't display the name due to
256 // https://github.com/rust-lang/rust-analyzer/issues/8092
257 #[doc = stringify!($name)]
258 #[doc = "action generated by `gpui::actions!`"]
259 #[derive(::std::clone::Clone,::std::cmp::PartialEq, ::std::default::Default)]
260 pub struct $name;
261
262 gpui::__impl_action!($namespace, $name, $name,
263 fn build(_: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
264 Ok(Box::new(Self))
265 },
266 fn action_json_schema(
267 _: &mut gpui::private::schemars::gen::SchemaGenerator,
268 ) -> Option<gpui::private::schemars::schema::Schema> {
269 None
270 }
271 );
272
273 gpui::register_action!($name);
274 )*
275 };
276}
277
278/// Defines and registers a unit struct that can be used as an actions, with a name that differs
279/// from it's type name.
280///
281/// To use more complex data types as actions, and rename them use `impl_action_as!`
282#[macro_export]
283macro_rules! action_as {
284 ($namespace:path, $name:ident as $visual_name:ident) => {
285 // Unfortunately rust-analyzer doesn't display the name due to
286 // https://github.com/rust-lang/rust-analyzer/issues/8092
287 #[doc = stringify!($name)]
288 #[doc = "action generated by `gpui::action_as!`"]
289 #[derive(::std::clone::Clone, ::std::cmp::PartialEq, ::std::default::Default)]
290 pub struct $name;
291
292 gpui::__impl_action!(
293 $namespace,
294 $name,
295 $visual_name,
296 fn build(
297 _: gpui::private::serde_json::Value,
298 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
299 Ok(Box::new(Self))
300 },
301 fn action_json_schema(
302 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
303 ) -> Option<gpui::private::schemars::schema::Schema> {
304 None
305 }
306 );
307
308 gpui::register_action!($name);
309 };
310}
311
312/// Defines and registers a unit struct that can be used as an action, with some deprecated aliases.
313#[macro_export]
314macro_rules! action_aliases {
315 ($namespace:path, $name:ident, [$($alias:ident),* $(,)?]) => {
316 // Unfortunately rust-analyzer doesn't display the name due to
317 // https://github.com/rust-lang/rust-analyzer/issues/8092
318 #[doc = stringify!($name)]
319 #[doc = "action, generated by `gpui::action_aliases!`"]
320 #[derive(
321 ::std::cmp::PartialEq,
322 ::std::clone::Clone,
323 ::std::default::Default,
324 ::std::fmt::Debug,
325 gpui::private::serde_derive::Deserialize,
326 gpui::private::schemars::JsonSchema,
327 )]
328 #[serde(crate = "gpui::private::serde")]
329 pub struct $name;
330
331 gpui::__impl_action!(
332 $namespace,
333 $name,
334 $name,
335 fn build(
336 _: gpui::private::serde_json::Value,
337 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
338 Ok(Box::new(Self))
339 },
340 fn action_json_schema(
341 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
342 ) -> Option<gpui::private::schemars::schema::Schema> {
343 None
344
345 },
346 fn deprecated_aliases() -> &'static [&'static str] {
347 &[
348 $(concat!(stringify!($namespace), "::", stringify!($alias))),*
349 ]
350 }
351 );
352
353 gpui::register_action!($name);
354 };
355}
356
357/// Registers the action and implements the Action trait for any struct that implements Clone,
358/// Default, PartialEq, serde_deserialize::Deserialize, and schemars::JsonSchema.
359///
360/// Fields and variants that don't make sense for user configuration should be annotated with
361/// #[serde(skip)].
362#[macro_export]
363macro_rules! impl_actions {
364 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
365 $(
366 gpui::__impl_action!($namespace, $name, $name,
367 fn build(value: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
368 Ok(std::boxed::Box::new(gpui::private::serde_json::from_value::<Self>(value)?))
369 },
370 fn action_json_schema(
371 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
372 ) -> Option<gpui::private::schemars::schema::Schema> {
373 Some(<Self as gpui::private::schemars::JsonSchema>::json_schema(
374 generator,
375 ))
376 }
377 );
378
379 gpui::register_action!($name);
380 )*
381 };
382}
383
384/// Implements the Action trait for internal action structs that implement Clone, Default,
385/// PartialEq. The purpose of this is to conveniently define values that can be passed in `dyn
386/// Action`.
387///
388/// These actions are internal and so are not registered and do not support deserialization.
389#[macro_export]
390macro_rules! impl_internal_actions {
391 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
392 $(
393 gpui::__impl_action!($namespace, $name, $name,
394 fn build(value: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
395 gpui::Result::Err(gpui::private::anyhow::anyhow!(
396 concat!(
397 stringify!($namespace),
398 "::",
399 stringify!($visual_name),
400 " is an internal action, so cannot be built from JSON."
401 )))
402 },
403 fn action_json_schema(
404 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
405 ) -> Option<gpui::private::schemars::schema::Schema> {
406 None
407 }
408 );
409 )*
410 };
411}
412
413/// Implements the Action trait for a struct that implements Clone, Default, PartialEq, and
414/// serde_deserialize::Deserialize. Allows you to rename the action visually, without changing the
415/// struct's name.
416///
417/// Fields and variants that don't make sense for user configuration should be annotated with
418/// #[serde(skip)].
419#[macro_export]
420macro_rules! impl_action_as {
421 ($namespace:path, $name:ident as $visual_name:tt ) => {
422 gpui::__impl_action!(
423 $namespace,
424 $name,
425 $visual_name,
426 fn build(
427 value: gpui::private::serde_json::Value,
428 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
429 Ok(std::boxed::Box::new(
430 gpui::private::serde_json::from_value::<Self>(value)?,
431 ))
432 },
433 fn action_json_schema(
434 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
435 ) -> Option<gpui::private::schemars::schema::Schema> {
436 Some(<Self as gpui::private::schemars::JsonSchema>::json_schema(
437 generator,
438 ))
439 }
440 );
441
442 gpui::register_action!($name);
443 };
444}
445
446#[doc(hidden)]
447#[macro_export]
448macro_rules! __impl_action {
449 ($namespace:path, $name:ident, $visual_name:tt, $($items:item),*) => {
450 impl gpui::Action for $name {
451 fn name(&self) -> &'static str
452 {
453 concat!(
454 stringify!($namespace),
455 "::",
456 stringify!($visual_name),
457 )
458 }
459
460 fn debug_name() -> &'static str
461 where
462 Self: ::std::marker::Sized
463 {
464 concat!(
465 stringify!($namespace),
466 "::",
467 stringify!($visual_name),
468 )
469 }
470
471 fn partial_eq(&self, action: &dyn gpui::Action) -> bool {
472 action
473 .as_any()
474 .downcast_ref::<Self>()
475 .map_or(false, |a| self == a)
476 }
477
478 fn boxed_clone(&self) -> std::boxed::Box<dyn gpui::Action> {
479 ::std::boxed::Box::new(self.clone())
480 }
481
482 fn as_any(&self) -> &dyn ::std::any::Any {
483 self
484 }
485
486 $($items)*
487 }
488 };
489}
490
491mod no_action {
492 use crate as gpui;
493 use std::any::Any as _;
494
495 actions!(zed, [NoAction]);
496
497 /// Returns whether or not this action represents a removed key binding.
498 pub fn is_no_action(action: &dyn gpui::Action) -> bool {
499 action.as_any().type_id() == (NoAction {}).type_id()
500 }
501}